IRIX 6.4 Development Libraries

home *** CD-ROM | disk | FTP | other *** search

/ IRIX 6.4 Development Libraries / SGI IRIX 6.4 Development Libraries.iso / docs6.4 / relnotes / dmedia_dev / ch05.z / ch05

Wrap

Text File | 1997-09-04 | 10.6 KB | 265 lines

- 1 - 5. _A_u_d_i_o__L_i_b_r_a_r_y This chapter lists information about the IRIS Audio Library (AL) 2.0 programming interface included in the IRIS Digital Media Development Environment. It includes changes, additions, and bug fixes since the IRIX 6.2 and 6.3 releases, known problems, workarounds, and caveats. The IRIS Audio Library 2.0 is a C language library that provides basic audio I/O, hardware control and synchronization capabilities to applications. The Audio Library is shipped as a dynamic shared library (/_u_s_r/_l_i_b/_l_i_b_a_u_d_i_o._s_o) included with the IRIX Development Option software. At the time of this release, the _I_R_I_S _D_i_g_i_t_a_l _M_e_d_i_a _P_r_o_g_r_a_m_m_i_n_g _G_u_i_d_e contains a description of the previous version of the AL (1.0). AL 1.0 programs will continue to work on AL 2.0-equipped systems. Most of the concepts are quite similar between the two AL versions, so the _D_i_g_i_t_a_l _M_e_d_i_a _P_r_o_g_r_a_m_m_i_n_g _G_u_i_d_e remains a valuable reference. We intend to update this programming guide at the earliest opportunity. The on-line manual page _A_L_i_n_t_r_o(_3_d_m) contains a short overview of AL 2.0 library functionality and a complete list of the procedure calls. Manual pages for both AL 2.0 calls and AL 1.0 calls are included. 5.1 _C_h_a_n_g_e_s__a_n_d__A_d_d_i_t_i_o_n_s IRIX 6.3 comes with an entirely new version of the Audio Library. This version remains backwards-compatible with previous versions of the Audio Library; all the older AL functions are provided and supported. However, a new set of function calls are included in the library. This section provides an overview of the features available with the new calls. +o AL 2.0 calls conform to the OpenGL capitalization conventions. For example, the new version of _A_L_o_p_e_n_p_o_r_t() is called _a_l_O_p_e_n_P_o_r_t(). +o AL 2.0 calls all use units of sample frames. This is consistent with the other digital media libraries. Where necessary, the new AL function call names have been changed to indicate this; for example, the new equivalent of _A_L_w_r_i_t_e_s_a_m_p_s() is called _a_l_W_r_i_t_e_F_r_a_m_e_s(). - 2 - +o The new audio driver supports multiple independent audio input and output devices on the same system. Applications written with the new AL can address multiple devices simultaneously. Old AL applications can address only the default input device and default output device. These devices can be set via _a_p_a_n_e_l, or by any new AL application. See the _a_l_P_a_r_a_m_s man page for information on default devices. +o The new audio driver maintains independent gain values for each input source. This means users seldom need to adjust the input gain when changing input sources. Now when a user selects a new input source, the gain will automatically revert to its value when that source was previously selected. +o AL 2.0 provides a scalable, device-independent hardware control model. Parameter/value lists and the functions which use them have changed substantially. See the _a_l_P_a_r_a_m_s, _a_l_S_e_t_P_a_r_a_m_s, and _a_l_G_e_t_P_a_r_a_m_s man pages for more information. +o AL 2.0 introduces new functions for writing zero-valued sample-frames (_a_l_Z_e_r_o_F_r_a_m_e_s(_3_d_m)) and for discarding sample-frames from an input or output port (_a_l_D_i_s_c_a_r_d_F_r_a_m_e_s(_3_d_m)). The latter function satisfies request-for-enhancement (RFE) 374702. +o AL 2.0 removes the minimum queuesize limit (see _a_l_S_e_t_Q_u_e_u_e_S_i_z_e(_3_d_m)). This satisfies RFE 158615. +o In AL 2.0, the printing error handler is off by default. See _a_l_S_e_t_E_r_r_o_r_H_a_n_d_l_e_r(_3_d_m). Note that AL 1.0 programs relinked with AL 2.0 will acquire this behavior. +o AL 2.0 provides _a_l_G_e_t_E_r_r_o_r_S_t_r_i_n_g(_3_d_m), which returns a text string corresponding to any AL error code. This simplifies the task of handling function call failures. +o IRIX 6.3 includes a new version of _a_p_a_n_e_l, the audio control panel. This version supports multiple input and output devices. 5.2 _C_o_m_p_a_t_i_b_i_l_i_t_y__I_s_s_u_e_s This section lists the known compatibility issues between AL 2.0 and previous versions of the AL. AL 2.0 implements many old AL functions as wrappers around new AL equivalents. Older AL programs relinked against AL - 3 - 2.0 will thus automatically acquire some of the performance improvements, enhancements and bug fixes in AL 2.0. However, there are some caveats: +o AL 2.0 is a shared library. Previous versions of the AL were statically linked. AL programs compiled or linked under IRIX 6.3 cannot be run under previous versions of IRIX. +o _A_L_w_r_i_t_e_s_a_m_p_s() and _A_L_r_e_a_d_s_a_m_p_s() are internally implemented in terms of the newer _a_l_W_r_i_t_e_F_r_a_m_e_s() and _a_l_R_e_a_d_F_r_a_m_e_s(). While this provides some performance improvements, since the new functions are smaller and faster, it removes the ability to read and write partial sample frames on stereo ports. +o The default behavior for AL error handling is now silence. Older versions of the AL would print messages to the screen when an AL call failed. Unless you call _a_l_S_e_t_E_r_r_o_r_H_a_n_d_l_e_r(_3_d_m) to install your own error handler or to turn on printing messages, AL calls will no longer print messages when they fail. Following are compatibility issues for all old applications running on IRIX 6.3, even if not relinked with AL 2.0: +o The old AL sample-rate AL_RATE_INPUTRATE has different semantics with the new audio driver. Setting the output rate to AL_RATE_INPUTRATE will cause the rate on the default output device to match the rate on the default input device, if possible. But the output rate will not track further changes to the input rate. Note also that on some machines with multiple audio subsystems, it may not be possible to match the two rates; the default output device and default input device may not support the same set of rates, or may not be able to access the same timebase. +o Because the new driver maintains independent gain values for each input source, changing the input source now changes the input gain value. Old applications which expect the gain value to remain constant across input source changes may have issues under IRIX 6.3. 5.3 _B_u_g__F_i_x_e_s This section lists the bugs fixed since the last release of the IRIS Audio Library. Some of the descriptions are followed by a Silicon Graphics bug report number in the form (SCR XXXX). - 4 - +o A problem existed in previous releases of IRIX where a rare race-condition could panic the system if a multi- process application closed an audio port in one process while it attempted to use the port in another process. (SCR 334606) +o In four-channel mode, at sample-rates derived from 44.1kHz, under certain conditions the front and back stereo pairs could become swapped. This has been fixed (SCR 315007, 375810). 5.4 _K_n_o_w_n__P_r_o_b_l_e_m_s__a_n_d__W_o_r_k_a_r_o_u_n_d_s This section lists problems in the Audio Library software and ways to work around them. +o When there is nothing physically connected to the digital I/O jack, it is meaningless to set the system sample rates in the following three ways: +o output sample rate set to match the input sample rate while using digital input as the system input. +o input sample rate set to the digital rate and the output rate set to match the input rate. +o input sample rate set to the digital rate and the output rate set to the digital input rate. +o When the system is placed in one of these states, the behavior cannot be predicted. Performing any of the actions listed above should be avoided by application programs. 5.5 _P_r_o_g_r_a_m_m_i_n_g__E_x_a_m_p_l_e_s The _d_m_e_d_i_a__d_e_v._s_r_c._e_x_a_m_p_l_e_s subsystem contains several source code examples for programming with the Audio Library. The source code is available in the directory /_u_s_r/_s_h_a_r_e/_s_r_c/_d_m_e_d_i_a/_a_u_d_i_o. The _d_m_e_d_i_a__d_e_v._s_r_c._t_o_o_l_s subsystem includes the source code for the standard aaaauuuuddddiiiiooooppppaaaannnneeeellll((((1111)))) and ssssoooouuuunnnnddddppppllllaaaayyyyeeeerrrr((((1111)))) tools which are shipped with IRIX 6.2 and later. The source code is installed in the directories /_u_s_r/_s_h_a_r_e/_s_r_c/_d_m_e_d_i_a/{_a_u_d_i_o_p_a_n_e_l,_s_o_u_n_d_p_l_a_y_e_r}.